// API: 证书相关接口
import { apiClient } from '@/utils/require'

/**
 * 证书类型定义
 */
export interface Certificate {
  id: number
  sort: string       // 类别
  name: string       // 证书名称
  ranks: string      // 级别（国家级、省级、校级等）
  classes: string    // 等级（一等奖、二等奖等）
  grade: number      // 对应分数
}

export interface PaginatedResponse<T> {
  count: number
  next: string | null
  previous: string | null
  results: T[]
}

/**
 * 证书管理API（证书类型字典）
 * 
 * API说明：
 * - 基础路径：/api/certificates/
 * - 认证方式：Token认证
 * - 权限控制：
 *   - 查看证书：所有已认证用户
 *   - 创建/修改/删除：仅管理员
 * - 用途：证书类型字典，用于附加分审查时选择证书类型及自动匹配分数
 */
export const certificateAPI = {
  /**
   * 获取证书列表
   * 
   * 接口：GET /api/certificates/
   * 权限：已认证用户
   * 
   * @param params 查询参数
   * @param params.page 页码
   * @param params.page_size 每页数量
   * @param params.search 搜索关键词（证书名称）
   * @param params.sort 类别筛选（如：学科竞赛、文体活动）
   * @param params.ranks 级别筛选（如：国家级、省级、校级）
   * @param params.classes 等级筛选（如：一等奖、二等奖、三等奖）
   * 
   * @returns 证书类型列表（包含对应分数）
   * @example
   * // 查询国家级证书
   * certificateAPI.getCertificateList({ ranks: '国家级' })
   */
  getCertificateList: (params?: {
    page?: number
    page_size?: number
    search?: string
    sort?: string      // 类别筛选
    ranks?: string     // 级别筛选
    classes?: string   // 等级筛选
  }) => {
    return apiClient.get<PaginatedResponse<Certificate>>('/certificates/', { params })
  },

  /**
   * 获取证书详情
   * 
   * 接口：GET /api/certificates/{id}/
   * 权限：已认证用户
   * 
   * @param id 证书ID
   * @returns 证书完整信息（类别、名称、级别、等级、对应分数）
   */
  getCertificateDetail: (id: number) => {
    return apiClient.get<Certificate>(`/certificates/${id}/`)
  },

  /**
   * 创建证书类型
   * 
   * 接口：POST /api/certificates/
   * 权限：仅管理员
   * 
   * @param data 证书数据
   * @param data.sort 类别（必填，如：学科竞赛）
   * @param data.name 证书名称（必填）
   * @param data.ranks 级别（必填，如：国家级）
   * @param data.classes 等级（必填，如：一等奖）
   * @param data.grade 对应分数（必填）
   * 
   * @returns 创建成功的证书信息
   */
  createCertificate: (data: Omit<Certificate, 'id'>) => {
    return apiClient.post('/certificates/', data)
  },

  /**
   * 更新证书信息（完整更新）
   * 
   * 接口：PUT /api/certificates/{id}/
   * 权限：仅管理员
   * 
   * @param id 证书ID
   * @param data 完整的证书数据
   * @returns 更新后的证书信息
   */
  updateCertificate: (id: number, data: Partial<Certificate>) => {
    return apiClient.put(`/certificates/${id}/`, data)
  },

  /**
   * 部分更新证书（推荐）
   * 
   * 接口：PATCH /api/certificates/{id}/
   * 权限：仅管理员
   * 
   * @param id 证书ID
   * @param data 需要更新的字段
   * @returns 更新后的证书信息
   * @example
   * // 仅更新分数
   * certificateAPI.patchCertificate(1, { grade: 10 })
   */
  patchCertificate: (id: number, data: Partial<Certificate>) => {
    return apiClient.patch(`/certificates/${id}/`, data)
  },

  /**
   * 删除证书
   * 
   * 接口：DELETE /api/certificates/{id}/
   * 权限：仅管理员
   * 
   * @param id 证书ID
   * @returns 204 No Content
   */
  deleteCertificate: (id: number) => {
    return apiClient.delete(`/certificates/${id}/`)
  }
}

export default certificateAPI
